Pokemon XD PC port - Linux test build 0.4.2
=================================================

THIS IS A TEST BUILD. It was built and tested inside Windows' Linux layer (WSL 2, Ubuntu 24.04), where
the picture is drawn by the processor, not by a graphics card. It has NEVER been run on a real Linux
PC with a real graphics card: you may be the first. Whatever happens, please send a report (below).

What you need
-------------
- A 64-bit PC (x86-64) with a Linux of about 2024 or newer (built on Ubuntu 24.04, glibc 2.39; an older
  system answers "version GLIBC_2.xx not found").
- A graphics card with a Vulkan driver (Mesa or the maker's own). OpenGL ES 3.1 is the fall-back.
- Your own copy of Pokemon XD: Gale of Darkness (USA version, game ID GXXE01) as a disc image file
  (.iso, .rvz, .gcm, ...). Nothing from the game comes with this program, and your disc image is never
  changed.
- System libraries. The program itself needs only these (every desktop system has them):
      libc.so.6                    libc6
      libgcc_s.so.1                libgcc-s1
      libm.so.6                    libc6
      libstdc++.so.6               libstdc++6
      libz.so.1                    zlib1g
  The window, sound and graphics parts are loaded when the game starts, from what your desktop has
  anyway (X11 or Wayland, PipeWire / PulseAudio / ALSA, Vulkan). On Ubuntu / Debian, if something is
  missing, this installs all of it:
      sudo apt install zlib1g libx11-6 libxext6 libxrandr2 libxcursor1 libxi6 libxfixes3 libxss1 \
          libxkbcommon0 libwayland-client0 libdecor-0-0 libpulse0 libasound2t64 libvulkan1 \
          mesa-vulkan-drivers zenity
  (libasound2 instead of libasound2t64 before Ubuntu 24.04. zenity is only for the "choose your disc
  image" window on desktops without a file chooser service.)

How to start it
---------------
Unpack the folder anywhere (keep "game" next to "Pokemon XD.sh"), then either
  - double-click "Pokemon XD.sh" (if your file manager asks: "Run"): the launcher opens. On its Disc
    page press "Choose..." and pick your disc image, then press Play. Or
  - in a terminal, inside the folder, straight into the game without the launcher:
        ./"Pokemon XD.sh" "/home/you/Games/Pokemon XD.iso"
The disc image is checked (a minute the first time) and remembered: the next start needs no file.
If nothing seems to happen, start it from a terminal: every problem the programs can name is printed
there. If the file-choosing window does not appear, give the disc image on the command line as above.
If the launcher itself does not open or looks wrong, please tell us, and start the game without it:
        XD_NO_LAUNCHER=1 ./"Pokemon XD.sh"

The launcher (new on Linux in this build, and like everything here never run on a real Linux desktop)
has these pages: Disc, Preset, Settings, Controls, Mods, Save (several saves, backups), Reports (list,
Export), and the "Version and updates" card on the Disc page: the launcher asks once whether it may
check for updates, tells you what is new and asks before downloading anything (it needs the program
"curl", which nearly every desktop has); an update is installed next to this one (a folder
"game-<version>" and the file game_folder.txt, both beside "Pokemon XD.sh") and "Go back" works. Your
saves and settings are never touched. Pictures for the launcher's background are drawn by the game
from your disc the first time. Not there on Linux yet, and not shown: choosing the window's icon,
preparing the shaders before the first start. "Open folder" buttons use your desktop's xdg-open; without it a small
window tells you where the folder is. Deleting a save in the launcher moves it to your desktop's trash
(~/.local/share/Trash). Shortcut buttons write a ".desktop" file (your desktop may ask you to allow
starting it).
The first start plays exactly like the GameCube ("Original"); improvements are settings you switch on
in the launcher, or in the game itself: SETTINGS after EXIT in the field menu and left of OPTIONS in
the title menu.

Controls: a controller is used when one is plugged in. Keyboard: arrow keys = the stick, X = A,
Z = B, C = X, S = Y, D = Z, Q and W = L and R, Enter = Start, T F G H = the + pad, I J K L = the
C stick.
Keys of the port: F10 bug report, F11 mark in the recording, F12 screenshot, Alt+Enter full screen.

Where your things are kept
--------------------------
    ~/.local/share/Pokemon XD
(or $XDG_DATA_HOME/Pokemon XD if you have set that): settings.ini, the memory card with your save
(USA/Card A), save_backups, logs, recordings, reports, screenshots. Deleting this program's folder
doesn't touch them. Portable use: a file named data_location.json next to game/xd containing
    {"version": 1, "mode": "portable"}
keeps everything in game/portable instead.
The shader cache (not important, made again when missing) is in the same folder.

How to send a report
--------------------
When something looks, sounds or plays wrong: press F10 at that moment. The window title says "bug
report saved". The game writes
    ~/.local/share/Pokemon XD/reports/report_<date>_<time>.zip
with a picture of the game at that moment, the recording of your button presses up to it (we can play
your session again from it), the end of the log, your settings and a short info.txt. Send that zip
file and say in a sentence or two what was wrong. Nothing is ever sent by the program itself.
The zip holds: your button presses, your settings, the log (which names folders of your PC, so your
user name can be in it) and one picture of the game. It does not hold your save or your disc.
If the game crashes or freezes, it writes such a report by itself (report_..._crash, _stop or
_stuck) with the chain of calls instead of a picture: please send that too.
If the game does not start at all there is no report: start it from a terminal and send what it
printed, plus the newest file in ~/.local/share/Pokemon XD/logs if there is one.
Useful to add: your distribution and version, desktop (GNOME, KDE...; Wayland or X11), graphics card
and driver (the output of: vulkaninfo --summary).

Known on Linux (this build)
---------------------------
- Never run on real graphics hardware (see the top). Speed, picture faults and sound stutter on your PC
  are exactly what we want to hear about.
- The launcher is new here and was only ever seen in screenshots made by the program itself inside
  WSL. Its update page is not there on Linux.
- The F10 / F12 picture is the game's own picture (640x480 times your resolution setting), taken a
  moment after the key press. When one of the port's own screens is open (SETTINGS, the New Game
  setup, the developer menu), that screen is drawn over it again by the program, at the window's
  size: positions and texts are right, single pixels can differ from what your screen showed.
  Automatic crash reports have no picture. With the OpenGL ES fall-back (no Vulkan) there is no
  picture at all: the report is still written, and still useful.
- Not on Linux yet (test and developer aids, each says so when asked): XD_RENDER_ICON, XD_WATCH,
  XD_SAMPLE, XD_STATE_NAME_RVAS, other threads' call stacks in a "stuck" report, frame capture for
  videos (XD_CAPTURE_DIR).
- If the picture stays black or the window never appears, the graphics driver was not accepted. Try
      SDL_VIDEODRIVER=x11 ./"Pokemon XD.sh"         (on a Wayland desktop)
      XD_GPU_BACKEND=vulkan ./"Pokemon XD.sh"       or  XD_GPU_BACKEND=opengles
  and tell us which one worked.
- Sound: in our tests inside WSL a few short gaps happened in real-time play (see docs). Tell us if
  you hear crackling or gaps, and whether your system uses PipeWire or PulseAudio.

The "game" folder
-----------------
xd (the game), the libraries built with it, the list of drawing settings its shaders are prepared from
(initial_pipeline_cache.db; no game data), and the licences of the parts made by others
(game/licenses). xd is not stripped of its debug information on purpose: the game looks up its own
variables by name in it, and crash reports are readable because of it.
